Composite bit values used in val3 for futex() operation FUTEX_WAKE_OP. More...

#include <futex.hxx>

Inheritance diagram for clues::item::FutexWakeOperation:

Public Types
enum class	Operation : uint32_t { SET = FUTEX_OP_SET , ADD = FUTEX_OP_ADD , OR = FUTEX_OP_OR , ANDN = FUTEX_OP_ANDN , XOR = FUTEX_OP_XOR }
	Atomic operation to be carried out on futex value. More...

enum class	Comparator : uint32_t { EQUAL = FUTEX_OP_CMP_EQ , UNEQUAL = FUTEX_OP_CMP_NE , LESS_THAN = FUTEX_OP_CMP_LT , LESS_EQUAL = FUTEX_OP_CMP_LE , GREATER_THAN = FUTEX_OP_CMP_GT , GREATER_EQUAL = FUTEX_OP_CMP_GE }

Public Types inherited from clues::SystemCallItem
enum class	Flag { DEFER_FILL = 1 << 0 }

using	Flags = cosmos::BitMask<Flag>

Public Member Functions
std::string	str () const override
	Returns a human readable string representation of the item.

void	processValue (const Tracee &) override
	Processes the value stored in m_val acc. to the actual item type.

auto	operation () const

auto	comparator () const

bool	doShiftArg () const

uint32_t	oparg () const

uint32_t	cmparg () const

Public Member Functions inherited from clues::item::ValueInParameter
	ValueInParameter (const std::string_view short_name, const std::string_view long_name={})

Public Member Functions inherited from clues::item::ValueParameter
	ValueParameter (const ItemType type, const std::string_view short_name, const std::string_view long_name={})

Public Member Functions inherited from clues::SystemCallItem
	SystemCallItem (const ItemType type, const std::string_view short_name={}, const std::string_view long_name={})
	Constructs a new SystemCallItem.

auto	type () const

bool	isIn () const

bool	isOut () const

bool	isInOut () const

bool	isReturnValue () const

void	fill (const Tracee &proc, const Word word)
	Fills the item from the given register data.

bool	needsUpdate () const
	Returns whether the item needs to be updated after the system call is finished.

std::string_view	shortName () const
	Returns the friendly short name for this item.

std::string_view	longName () const
	Returns the friendly long name for this item, if available, else the short name.

auto	hasLongName () const

bool	isZero () const
	Returns whether the parameter is set to 0 / NULL.

Word	value () const
	Returns the currently stored raw value of the item.

template<typename OTHER>
OTHER	valueAs () const
	Helper to cast the strongly typed `Word` `m_val` to other strong enum types.

ForeignPtr	asPtr () const

Flags	flags () const

bool	deferFill () const

Protected Attributes
Operation	m_op = Operation{0}

Comparator	m_comp = Comparator{0}

bool	m_shift_arg = false
	! Whether `oparg` is additionally replaced by `1 << oparg`.

uint32_t	m_oparg = 0
	! The operation argument used in `uaddr2 OP oparg`.

uint32_t	m_cmparg = 0
	! The comparison argument used in `oldval CMP cmparg`.

Protected Attributes inherited from clues::SystemCallItem
const SystemCall *	m_call = nullptr
	The system call context this item part of.

const ItemType	m_type
	The type of item.

std::string_view	m_short_name
	A human readable short name for the item, should be one word only.

std::string_view	m_long_name
	A human readable longer name for the item.

Word	m_val
	The raw register value for the item.

Flags	m_flags
	Flags influencing the processing of the item.

Additional Inherited Members
Protected Member Functions inherited from clues::SystemCallItem
virtual void	updateData (const Tracee &t)
	Called upon exit of the system call to update possible out parameters.

void	setSystemCall (const SystemCall &sc)
	Sets the system call context this item is a part of.

Detailed Description

Composite bit values used in val3 for futex() operation FUTEX_WAKE_OP.

This parameter defines scalar operations and comparisons to be carried out in the context of FutexOperation::Command::WAKE_OP.

The futex value found at uaddr2 is modified based on the given Operation and the result is written back to the futex in an atomic fashion.

The waiters blocked on uaddr are woken up.

The original futex value observed at uaddr2 is additionally compared based on the given Comparator. If the comparison yields true then a number of waiters blocked on uaddr2 are also woken up.

The information to the uaddr2 modification and comparison is stored in a uint32_t passed to the futex system call, whose details are made available in this type..

Definition at line 89 of file futex.hxx.

Member Enumeration Documentation

◆ Comparator

enum class clues::item::FutexWakeOperation::Comparator : uint32_t

strong

Enumerator
EQUAL	`oldval == cmparg`
UNEQUAL	`oldval != cmparg`
LESS_THAN	`oldval < cmparg`
LESS_EQUAL	`oldval <= cmparg`
GREATER_THAN	`oldval > cmparg`
GREATER_EQUAL	`oldval >= cmparg`

Definition at line 102 of file futex.hxx.

                              : uint32_t {
                EQUAL         = FUTEX_OP_CMP_EQ,  
                UNEQUAL       = FUTEX_OP_CMP_NE,  
                LESS_THAN     = FUTEX_OP_CMP_LT,  
                LESS_EQUAL    = FUTEX_OP_CMP_LE,  
                GREATER_THAN  = FUTEX_OP_CMP_GT,  
                GREATER_EQUAL = FUTEX_OP_CMP_GE,  
        };

◆ Operation

enum class clues::item::FutexWakeOperation::Operation : uint32_t

strong

Atomic operation to be carried out on futex value.

Enumerator
SET	assignment `uaddr2 = oparg`
ADD	addition `uaddr2 += oparg`
OR	bitwise or `uaddr2 \|= oparg`
ANDN	bitwise and of negated value `uaddr2 &= ~oparg`
XOR	bitwise XOR `uaddr ^= oparg`

Definition at line 94 of file futex.hxx.

                             : uint32_t {
                SET  = FUTEX_OP_SET,  
                ADD  = FUTEX_OP_ADD,  
                OR   = FUTEX_OP_OR,   
                ANDN = FUTEX_OP_ANDN, 
                XOR  = FUTEX_OP_XOR,  
        };

Constructor & Destructor Documentation

◆ FutexWakeOperation()

clues::item::FutexWakeOperation::FutexWakeOperation ( )

inlineexplicit

Definition at line 113 of file futex.hxx.

                                      :
                        ValueInParameter{"wake_op", "wake operation settings"} {
        }

Member Function Documentation

◆ cmparg()

uint32_t clues::item::FutexWakeOperation::cmparg ( ) const

inline

Definition at line 137 of file futex.hxx.

                                {
                return m_cmparg;
        }

◆ comparator()

auto clues::item::FutexWakeOperation::comparator ( ) const

inline

Definition at line 125 of file futex.hxx.

                                {
                return m_comp;
        }

◆ doShiftArg()

bool clues::item::FutexWakeOperation::doShiftArg ( ) const

inline

Definition at line 129 of file futex.hxx.

                                {
                return m_shift_arg;
        }

◆ oparg()

uint32_t clues::item::FutexWakeOperation::oparg ( ) const

inline

Definition at line 133 of file futex.hxx.

                               {
                return m_oparg;
        }

◆ operation()

auto clues::item::FutexWakeOperation::operation ( ) const

inline

Definition at line 121 of file futex.hxx.

                               {
                return m_op;
        }

◆ processValue()

void clues::item::FutexWakeOperation::processValue ( const Tracee & )

overridevirtual

Processes the value stored in m_val acc. to the actual item type.

This function is called for all parameter types upon entry to a system call, and for ItemType::RETVAL upon exit from a system call.

For parameters of ItemType::PARAM_OUT this callback can be used to reset any stored data to be filled in later when updateData() is called.

Reimplemented from clues::SystemCallItem.

Definition at line 86 of file futex.cxx.

                                                    {
        const auto raw = valueAs<uint32_t>();
        /*
         * the integer is structured like this:
         *
         * <4 bits Operation><4 bits Comparator><12 bits oparg><12 bits cmparg>
         *
         * where the upper bit of the operation is the optional "shift arg"
         * flag.
         */
 
        const auto op_bits = raw >> 28;
        /*
         * NOTE: there's a bug in man futex(2), which names FUTEX_OP_ARG_SHIFT
         * here instead.
         */
        m_op = Operation{op_bits & (~FUTEX_OP_OPARG_SHIFT)};
        m_shift_arg = op_bits & FUTEX_OP_OPARG_SHIFT;
        m_comp = Comparator{(raw >> 24) & 0xF};
        m_oparg = (raw >> 12) & 0xFFF;
        m_cmparg = raw & 0xFFF;
 
}

◆ str()

std::string clues::item::FutexWakeOperation::str ( ) const

overridevirtual

Returns a human readable string representation of the item.

This member function should be specialized in derived classes to output the item's data in a fashion suitable for the concrete item type.

Reimplemented from clues::SystemCallItem.

Definition at line 110 of file futex.cxx.

                                        {
        return cosmos::sprintf("{op=%s%s, cmp=%s, oparg=%u, cmparg=%u}",
                get_label(m_op).c_str(),
                m_shift_arg ? "|FUTEX_OP_OPARG_SHIFT" : "",
                get_label(m_comp).c_str(),
                m_oparg,
                m_cmparg);
}

Member Data Documentation

◆ m_cmparg

uint32_t clues::item::FutexWakeOperation::m_cmparg = 0

protected

! The comparison argument used in oldval CMP cmparg.

Definition at line 150 of file futex.hxx.

◆ m_comp

Comparator clues::item::FutexWakeOperation::m_comp = Comparator{0}

protected

Definition at line 144 of file futex.hxx.

144{0};

◆ m_op

Operation clues::item::FutexWakeOperation::m_op = Operation{0}

protected

Definition at line 143 of file futex.hxx.

143{0};

◆ m_oparg

uint32_t clues::item::FutexWakeOperation::m_oparg = 0

protected

! The operation argument used in uaddr2 OP oparg.

Definition at line 148 of file futex.hxx.

◆ m_shift_arg

bool clues::item::FutexWakeOperation::m_shift_arg = false

protected

! Whether oparg is additionally replaced by 1 << oparg.

Definition at line 146 of file futex.hxx.

The documentation for this class was generated from the following files:

include/items/futex.hxx
src/items/futex.cxx

Public Types

Public Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Comparator

◆ Operation

Constructor & Destructor Documentation

◆ FutexWakeOperation()

Member Function Documentation

◆ cmparg()

◆ comparator()

◆ doShiftArg()

◆ oparg()

◆ operation()

◆ processValue()

◆ str()

Member Data Documentation

◆ m_cmparg

◆ m_comp

◆ m_op

◆ m_oparg

◆ m_shift_arg