volatile

The correct use of volatile is necessary to prevent elusive bugs. It instructs the compiler to use exact semantics for the declared objects--in particular, to not optimize away or reorder accesses to the object. There are two instances where device drivers must use the volatile qualifier:

1. When data refers to an external hardware device register (memory that has side effects other than just storage). Note, however, that if the DDI data access functions are used to access device registers, it is not necessary to use volatile.

2. When data refers to global memory that is accessible by more than one thread, is not protected by locks, and therefore is relying on the sequencing of memory accesses

   In general, drivers should not qualify a variable as volatile if it is merely accessible by more than one thread and protected from conflicting access by synchronization routines.

   The following example uses volatile. A busy flag is used to prevent a thread from continuing while the device is busy and the flag is not protected by a lock:

   	while (busy) {
     		/* do something else */
     	}

   The testing thread will continue when another thread turns off the busy flag:

   	busy = 0;

   However, since busy is accessed frequently in the testing thread, the compiler may optimize the test by placing the value of busy in a register, then test the contents of the register without reading the value of busy in memory before every test. The testing thread would never see busy change and the other thread would only change the value of busy in memory, resulting in deadlock. Declaring the busy flag as volatile forces its value to be read before each test.

   ---

   Note -

   It would probably be preferable to use a condition variable mutex, discussed under "Condition Variables" rather than the busy flag in this example.

   ---

   It is also recommended that the volatile qualifier be used in such a way as to avoid the risk of accidental omission. For example, this code

   	struct device_reg {
    		volatile uint8_t csr;
    		volatile uint8_t data;
    	};
    	struct device_reg *regp;

   is recommended over:

   	struct device_reg {
    		uint8_t csr;
    		uint8_t data;
    	};
    	volatile struct device_reg *regp;

   Although the two examples are functionally equivalent, the second one requires the writer to ensure that volatile is used in every declaration of type struct device_reg. The first example results in the data being treated as volatile in all declarations and is therefore preferred. Note as mentioned above, that the use of the DDI data access functions to access device registers makes it unnecessary to qualify variables as volatile.