.TH "avr_sleep" 3avr "Fri Nov 24 2023 23:59:10" "Version 2.0.0" "avr-libc" \" -*- nroff -*-
.ad l
.nh
.SH NAME
avr_sleep \- <avr/sleep\&.h>: Power Management and Sleep Modes
.SH SYNOPSIS
.br
.PP
.SS "Functions"

.in +1c
.ti -1c
.RI "void \fBsleep_enable\fP (void)"
.br
.ti -1c
.RI "void \fBsleep_disable\fP (void)"
.br
.ti -1c
.RI "void \fBsleep_cpu\fP (void)"
.br
.ti -1c
.RI "void \fBsleep_mode\fP (void)"
.br
.ti -1c
.RI "void \fBsleep_bod_disable\fP (void)"
.br
.in -1c
.SH "Detailed Description"
.PP 

.PP
.nf
#include <avr/sleep\&.h>

.fi
.PP
.PP
Use of the \fCSLEEP\fP instruction can allow an application to reduce its power comsumption considerably\&. AVR devices can be put into different sleep modes\&. Refer to the datasheet for the details relating to the device you are using\&.
.PP
There are several macros provided in this header file to actually put the device into sleep mode\&. The simplest way is to optionally set the desired sleep mode using \fCset_sleep_mode()\fP (it usually defaults to idle mode where the CPU is put on sleep but all peripheral clocks are still running), and then call \fC\fBsleep_mode()\fP\fP\&. This macro automatically sets the sleep enable bit, goes to sleep, and clears the sleep enable bit\&.
.PP
Example: 
.PP
.nf
#include <avr/sleep\&.h>

\&.\&.\&.
  set_sleep_mode(<mode>);
  sleep_mode();

.fi
.PP
.PP
Note that unless your purpose is to completely lock the CPU (until a hardware reset), interrupts need to be enabled before going to sleep\&.
.PP
As the \fC\fBsleep_mode()\fP\fP macro might cause race conditions in some situations, the individual steps of manipulating the sleep enable (SE) bit, and actually issuing the \fCSLEEP\fP instruction, are provided in the macros \fC\fBsleep_enable()\fP\fP, \fC\fBsleep_disable()\fP\fP, and \fC\fBsleep_cpu()\fP\fP\&. This also allows for test-and-sleep scenarios that take care of not missing the interrupt that will awake the device from sleep\&.
.PP
Example: 
.PP
.nf
#include <avr/interrupt\&.h>
#include <avr/sleep\&.h>

\&.\&.\&.
  set_sleep_mode(<mode>);
  cli();
  if (some_condition)
  {
    sleep_enable();
    sei();
    sleep_cpu();
    sleep_disable();
  }
  sei();

.fi
.PP
.PP
This sequence ensures an atomic test of \fCsome_condition\fP with interrupts being disabled\&. If the condition is met, sleep mode will be prepared, and the \fCSLEEP\fP instruction will be scheduled immediately after an \fCSEI\fP instruction\&. As the intruction right after the \fCSEI\fP is guaranteed to be executed before an interrupt could trigger, it is sure the device will really be put to sleep\&.
.PP
Some devices have the ability to disable the Brown Out Detector (BOD) before going to sleep\&. This will also reduce power while sleeping\&. If the specific AVR device has this ability then an additional macro is defined: \fC\fBsleep_bod_disable()\fP\fP\&. This macro generates inlined assembly code that will correctly implement the timed sequence for disabling the BOD before sleeping\&. However, there is a limited number of cycles after the BOD has been disabled that the device can be put into sleep mode, otherwise the BOD will not truly be disabled\&. Recommended practice is to disable the BOD (\fC\fBsleep_bod_disable()\fP\fP), set the interrupts (\fC\fBsei()\fP\fP), and then put the device to sleep (\fC\fBsleep_cpu()\fP\fP), like so:
.PP
.PP
.nf
#include <avr/interrupt\&.h>
#include <avr/sleep\&.h>

\&.\&.\&.
  set_sleep_mode(<mode>);
  cli();
  if (some_condition)
  {
    sleep_enable();
    sleep_bod_disable();
    sei();
    sleep_cpu();
    sleep_disable();
  }
  sei();
.fi
.PP
 
.SH "Function Documentation"
.PP 
.SS "void sleep_bod_disable (void)\fC [extern]\fP"
Disable BOD before going to sleep\&. Not available on all devices\&. 
.SS "void sleep_cpu (void)\fC [extern]\fP"
Put the device into sleep mode\&. The SE bit must be set beforehand, and it is recommended to clear it afterwards\&. 
.SS "void sleep_disable (void)\fC [extern]\fP"
Clear the SE (sleep enable) bit\&. 
.SS "void sleep_enable (void)\fC [extern]\fP"
Put the device in sleep mode\&. How the device is brought out of sleep mode depends on the specific mode selected with the set_sleep_mode() function\&. See the data sheet for your device for more details\&.
.PP
Set the SE (sleep enable) bit\&. 
.SS "void sleep_mode (void)\fC [extern]\fP"
Put the device into sleep mode, taking care of setting the SE bit before, and clearing it afterwards\&. 
.SH "Author"
.PP 
Generated automatically by Doxygen for avr-libc from the source code\&.