<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-1F280171-A3F3-4129-8DBE-3B1C4D629C68" xml:lang="en"><title>Atomic

Operations</title><shortdesc>Describes the new atomic operations added to <codeph>euser.dll</codeph> and

the kernel. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>An atomic operation is an operation that comprises two or more conditions.

When an atomic operation is executed and all conditions are met it results

in success; when one or more conditions are not met it results in failure.

The new atomic operations added to <codeph>euser.dll</codeph> and the kernel

replace the existing ones. The existing operation format is preserved <codeph>__e32_atomic_xxx_yyyZ</codeph> </p>

<p>In the above format: </p>

<ul>

<li><p>z specifies the size of the data type being operated on</p></li>

<li><p>yyy specifies the type of memory ordering that is to be enforced (with

memory barriers)</p></li>

<li><p>xxx specifies the operation that is to be performed. </p></li>

</ul>

<p>The following table outlines the types of memory ordering and operations

available.</p>

<table id="GUID-3F63C6B6-E16F-4418-90FF-2BFBED7AB096">

<tgroup cols="2"><colspec colname="col1" colwidth="0.33*"/><colspec colname="col2" colwidth="1.67*"/>

<tbody>

<row>

<entry nameend="col2" namest="col1"><b>Memory Ordering (yyy)</b></entry>

</row>

<row>

<entry><b>Name </b></entry>

<entry><b>Description</b></entry>

</row>

<row>

<entry>rlx</entry>

<entry>Relaxed memory ordering. In this type of ordering there is no fixed

order in which the atomic operation is observed in relation to other memory

operations.</entry>

</row>

<row>

<entry>acq</entry>

<entry>Acquire semantics. In this type of memory ordering a memory barrier

is placed after the atomic operation.</entry>

</row>

<row>

<entry>rel</entry>

<entry>Release semantics. In this type of ordering a memory barrier is executed

before the atomic operation.</entry>

</row>

<row>

<entry>ord</entry>

<entry>Fully ordered. In this type of ordering a memory barrier is executed

before and after the atomic operation.</entry>

</row>

<row>

<entry nameend="col2" namest="col1"><b>Operation (xxx)</b></entry>

</row>

<row>

<entry><b>Name</b></entry>

<entry><b>Description</b></entry>

</row>

<row>

<entry>load</entry>

<entry>Reads the contents of a location.</entry>

</row>

<row>

<entry>store</entry>

<entry>Writes to a location</entry>

</row>

<row>

<entry>swp</entry>

<entry>Swaps the contents of a specified memory location with a given parameter.</entry>

</row>

<row>

<entry>add</entry>

<entry>Adds a value to the contents of the specified memory location.</entry>

</row>

<row>

<entry>and</entry>

<entry>Logical AND.</entry>

</row>

<row>

<entry>ior</entry>

<entry>Logical OR.</entry>

</row>

<row>

<entry>xor</entry>

<entry>Logical XOR.</entry>

</row>

<row>

<entry>axo</entry>

<entry> AND then XOR</entry>

</row>

<row>

<entry>cas</entry>

<entry>Compare and Set<p>Compare the contents of the specified memory location

with another specified location. If the contents of both locations have the

same value, the contents of the original location is set to a specified value.</p></entry>

</row>

<row>

<entry>tau</entry>

<entry>Threshold and add unsigned<p>If the contents of a specified memory

location is greater than the specified threshold, then add the contents with

one parameter, otherwise add the contents to another. For this operation,

all the parameters are unsigned.</p></entry>

</row>

<row>

<entry>tas</entry>

<entry> Threshold and add signed<p>If the contents of a specified memory location

is greater than the specified threshold, then add the contents with one parameter,

otherwise add the contents to another. For this operation, all the parameters

are signed.</p></entry>

</row>

</tbody>

</tgroup>

</table>

<p>The meaning of each parameter, depends on the operation (xxx) (the argument

order is from left to right) :</p>

<table id="GUID-2CEA8D77-49CB-4C7B-953D-A811C208C6FC">

<tgroup cols="5"><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/><colspec colname="col4"/><colspec colname="col5"/>

<tbody>

<row>

<entry align="center"><b>Operation (xxx)</b></entry>

<entry align="center"><b>First argument</b></entry>

<entry align="center"><b>Second Argument</b></entry>

<entry align="center"><b>Third Argument</b></entry>

<entry align="center"><b>Fourth Argument</b></entry>

</row>

<row>

<entry align="center">load</entry>

<entry align="center">address of the data</entry>

<entry align="center">N/A</entry>

<entry align="center">N/A</entry>

<entry align="center">N/A</entry>

</row>

<row>

<entry align="center">store</entry>

<entry align="center">address of the data</entry>

<entry align="center">Data to be stored.</entry>

<entry align="center">N/A</entry>

<entry align="center">N/A</entry>

</row>

<row>

<entry align="center">swp</entry>

<entry align="center">address of the data</entry>

<entry align="center">Data to be swapped.</entry>

<entry align="center">N/A</entry>

<entry align="center">N/A</entry>

</row>

<row>

<entry align="center">cas</entry>

<entry align="center">address of the data</entry>

<entry align="center">Address of the data to be compared.</entry>

<entry align="center">New contents of the address specified in the first parameter,

if the comparison is true.</entry>

<entry align="center">N/A</entry>

</row>

<row>

<entry align="center">add</entry>

<entry align="center">address of the data</entry>

<entry align="center">Data to be added.</entry>

<entry align="center">N/A</entry>

<entry align="center">N/A</entry>

</row>

<row>

<entry align="center">and</entry>

<entry align="center">address of the data</entry>

<entry align="center">Data to be used in the AND operation .</entry>

<entry align="center">N/A</entry>

<entry align="center">N/A</entry>

</row>

<row>

<entry align="center">ior</entry>

<entry align="center">address of the data</entry>

<entry align="center">Data to be used in the OR operation.</entry>

<entry align="center">N/A</entry>

<entry align="center">N/A</entry>

</row>

<row>

<entry align="center">xor</entry>

<entry align="center">address of the data</entry>

<entry align="center">Data to be used in the XOR operation.</entry>

<entry align="center">N/A</entry>

<entry align="center">N/A</entry>

</row>

<row>

<entry align="center">axo</entry>

<entry align="center">address of the data</entry>

<entry align="center">Data to be used in the AND operation.</entry>

<entry align="center">Data to be used in the XOR operation.</entry>

<entry align="center">N/A</entry>

</row>

<row>

<entry align="center">tau</entry>

<entry align="center">address of the data</entry>

<entry align="center">Value of the threshold.</entry>

<entry align="center">See note 1.</entry>

<entry align="center">See note 2.</entry>

</row>

<row>

<entry align="center">tas</entry>

<entry align="center">address of the data</entry>

<entry align="center">Value of the threshold.</entry>

<entry align="center">See note 1.</entry>

<entry align="center">See note 2.</entry>

</row>

</tbody>

</tgroup>

</table>

<p><note>Note:</note></p>

<p> 1. Value to add if the value of the data pointed to by the address in

the first parameter, is equal to or greater than the threshold value</p>

<p>2. Value to add if the value of the data pointed to by the address in the

first parameter, is less than the threshold.</p>

<section id="GUID-C56AD38F-DF1F-4872-9BE9-C7A255695C26"><title>Example</title> 

     <p>An example of an atomic operation in use is :</p><codeblock xml:space="preserve">              if (__e32_atomic_tas_ord32(&amp;buffer.iDisplayDriverCount, 1, -1, 0) == 1)

                  {

                      // All drivers disconnected, deallocate memory.

                      ...

                  }</codeblock><p>In the above example we use a fully ordered

memory to compare a threshold value of 1. If the value of <codeph>&amp;buffer.iDisplayDriverCount</codeph> is

greater than or equal to 1 then it is added with -1 and the final value of <codeph>&amp;buffer.iDisplayDriverCount</codeph> is

returned. If the value of <codeph>&amp;buffer.iDisplayDriverCount</codeph> is

not greater than or equal to 1, the value of <codeph>&amp;buffer.iDisplayDriverCount</codeph> is

added with 0 and returned. The driver are disconnected when the returned value

is equal to 1.</p></section>

</conbody><related-links>

<link href="GUID-9D93F895-B975-4F2D-A2A3-817033EA5C12.dita"><linktext>Maintaining

Data Integrity Using Memory Barriers</linktext></link>

</related-links></concept>