|
|
|
|
.\"
|
|
|
|
|
.\" 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/
|
