diff options
Diffstat (limited to 'doc/ck_pr_rtm')
| -rw-r--r-- | doc/ck_pr_rtm | 112 |
1 files changed, 112 insertions, 0 deletions
diff --git a/doc/ck_pr_rtm b/doc/ck_pr_rtm new file mode 100644 index 0000000..53c31b6 --- /dev/null +++ b/doc/ck_pr_rtm @@ -0,0 +1,112 @@ +.\" +.\" Copyright 2013 Samy Al Bahra. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd December 17, 2013 +.Dt ck_pr_rtm 3 +.Sh NAME +.Nm ck_pr_rtm_begin , +.Nm ck_pr_rtm_end , +.Nm ck_pr_rtm_abort , +.Nm ck_pr_rtm_test +.Nd restricted transactional memory +.Sh LIBRARY +Concurrency Kit (libck, \-lck) +.Sh SYNOPSIS +.In ck_pr.h +.Ft unsigned int +.Fn ck_pr_rtm_begin "void" +.Ft void +.Fn ck_pr_rtm_end "void" +.Ft void +.Fn ck_pr_rtm_abort "const unsigned int status" +.Ft bool +.Fn ck_pr_rtm_test "void" +.Sh DESCRIPTION +These family of functions implement support for restricted +transactional memory, if available on the underlying platform. +Currently, support is only provided for Intel Haswell and +newer x86 microarchitectures that have the TSX-NI feature. +.Pp +The +.Fn ck_pr_rtm_begin +function returns CK_PR_RTM_STARTED if a transaction was successfully +started. In case of an abort, either internal (through a ck_pr_rtm_abort) +or external, program flow will return to the point which the function +was called except the return value will consist of a bitmap with one or +more of the following bits set: +.Bl -tag -width indent +.It CK_PR_RTM_EXPLICIT +Set if the transactionally was explicitly aborted through +.Fn ck_pr_rtm_abort . +.It CK_PR_RTM_RETRY +Set if the transaction failed but can still succeed if +retried. +.It CK_PR_RTM_CONFLICT +The transaction failed due to a conflict in one of the memory +addresses that are part of the working set of the transaction. +.It CK_PR_RTM_CAPACITY +Set if the architecture-defined transaction size limit was exceeded. +.It CK_PR_RTM_DEBUG +Set if a hardware breakpoint was triggered. +.It CK_PR_RTM_NESTED +Set if a nested transaction failed. +.El +.Pp +The user is also able to specify a one byte abort status +by calling +.Fn ck_pr_rtm_abort . +This status byte can be extracted by calling the +.Fn CK_PR_RTM_CODE +function with the return value of +.Fn ck_pr_rtm_begin +as an argument. The return value of +.Fn CK_PR_RTM_CODE +will be the value of this status byte. +For additional information, please see the Intel instruction +set manuals. +.Sh SEE ALSO +.Xr ck_pr_fence_load 3 , +.Xr ck_pr_fence_load_depends 3 , +.Xr ck_pr_fence_store 3 , +.Xr ck_pr_fence_memory 3 , +.Xr ck_pr_load 3 , +.Xr ck_pr_store 3 , +.Xr ck_pr_fas 3 , +.Xr ck_pr_faa 3 , +.Xr ck_pr_inc 3 , +.Xr ck_pr_dec 3 , +.Xr ck_pr_neg 3 , +.Xr ck_pr_not 3 , +.Xr ck_pr_sub 3 , +.Xr ck_pr_and 3 , +.Xr ck_pr_or 3 , +.Xr ck_pr_xor 3 , +.Xr ck_pr_add 3 , +.Xr ck_pr_btc 3 , +.Xr ck_pr_bts 3 , +.Xr ck_pr_btr 3 +.Pp +Additional information available at http://concurrencykit.org/ |