You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
163 lines
12 KiB
HTML
163 lines
12 KiB
HTML
<!-- HTML header for doxygen 1.8.7-->
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
|
<meta name="generator" content="Doxygen 1.6.3"/>
|
|
<!--BEGIN PROJECT_NAME--><title>avr-libc: avr-libc: <avr/lock.h>: Lockbit Support</title><!--END PROJECT_NAME-->
|
|
<!--BEGIN !PROJECT_NAME--><title>avr-libc: <avr/lock.h>: Lockbit Support</title><!--END !PROJECT_NAME-->
|
|
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="$relpath^jquery.js"></script>
|
|
<script type="text/javascript" src="$relpath^dynsections.js"></script>
|
|
$treeview
|
|
$search
|
|
$mathjax
|
|
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
|
|
$extrastylesheet
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
|
|
<!--BEGIN TITLEAREA-->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr style="height: 56px;">
|
|
<!--BEGIN PROJECT_LOGO-->
|
|
<td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td>
|
|
<!--END PROJECT_LOGO-->
|
|
<!--BEGIN PROJECT_NAME-->
|
|
<td style="padding-left: 0.5em;">
|
|
<div id="projectname">avr-libc
|
|
<!--BEGIN PROJECT_NUMBER--> <span id="projectnumber">2.0.0</span><!--END PROJECT_NUMBER-->
|
|
</div>
|
|
<!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
|
|
</td>
|
|
<!--END PROJECT_NAME-->
|
|
<!--BEGIN !PROJECT_NAME-->
|
|
<!--BEGIN PROJECT_BRIEF-->
|
|
<td style="padding-left: 0.5em;">
|
|
<div id="projectbrief">$projectbrief</div>
|
|
</td>
|
|
<!--END PROJECT_BRIEF-->
|
|
<!--END !PROJECT_NAME-->
|
|
<!--BEGIN DISABLE_INDEX-->
|
|
<!--BEGIN SEARCHENGINE-->
|
|
<td>$searchbox</td>
|
|
<!--END SEARCHENGINE-->
|
|
<!--END DISABLE_INDEX-->
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<table>
|
|
<tr>
|
|
<td align="left"><a href="http://www.nongnu.org/avr-libc/"><h2>AVR Libc Home Page</h2></a></td>
|
|
<td align="center" colspan=4><img src="avrs.png" alt="AVRs" align="middle" border="0"></td>
|
|
<td align="right"><a href="https://savannah.nongnu.org/projects/avr-libc/"><h2>AVR Libc Development Pages</h2></a></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" width="20%"><a href="index.html"><h2>Main Page</h2></a></td>
|
|
<td align="center" width="20%"><a href="pages.html"><h2>User Manual</h2></a></td>
|
|
<td align="center" width="20%"><a href="modules.html"><h2>Library Reference</h2></a></td>
|
|
<td align="center" width="20%"><a href="FAQ.html"><h2>FAQ</h2></a></td>
|
|
<td align="center" width="20%"><a href="group__demos.html"><h2>Example Projects</h2></a></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<!--END TITLEAREA-->
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.6.3 -->
|
|
<script type="text/javascript"><!--
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
|
--></script>
|
|
<div class="contents">
|
|
<h1><avr/lock.h>: Lockbit Support</h1><table border="0" cellpadding="0" cellspacing="0">
|
|
</table>
|
|
<dl class="user"><dt><b>Introduction</b></dt><dd></dd></dl>
|
|
<p>The Lockbit API allows a user to specify the lockbit settings for the specific AVR device they are compiling for. These lockbit settings will be placed in a special section in the ELF output file, after linking.</p>
|
|
<p>Programming tools can take advantage of the lockbit information embedded in the ELF file, by extracting this information and determining if the lockbits need to be programmed after programming the Flash and EEPROM memories. This also allows a single ELF file to contain all the information needed to program an AVR.</p>
|
|
<p>To use the Lockbit API, include the <<a class="el" href="io_8h.html">avr/io.h</a>> header file, which in turn automatically includes the individual I/O header file and the <<a class="el" href="lock_8h.html">avr/lock.h</a>> file. These other two files provides everything necessary to set the AVR lockbits.</p>
|
|
<dl class="user"><dt><b>Lockbit API</b></dt><dd></dd></dl>
|
|
<p>Each I/O header file may define up to 3 macros that controls what kinds of lockbits are available to the user.</p>
|
|
<p>If __LOCK_BITS_EXIST is defined, then two lock bits are available to the user and 3 mode settings are defined for these two bits.</p>
|
|
<p>If __BOOT_LOCK_BITS_0_EXIST is defined, then the two BLB0 lock bits are available to the user and 4 mode settings are defined for these two bits.</p>
|
|
<p>If __BOOT_LOCK_BITS_1_EXIST is defined, then the two BLB1 lock bits are available to the user and 4 mode settings are defined for these two bits.</p>
|
|
<p>If __BOOT_LOCK_APPLICATION_TABLE_BITS_EXIST is defined then two lock bits are available to set the locking mode for the Application Table Section (which is used in the XMEGA family).</p>
|
|
<p>If __BOOT_LOCK_APPLICATION_BITS_EXIST is defined then two lock bits are available to set the locking mode for the Application Section (which is used in the XMEGA family).</p>
|
|
<p>If __BOOT_LOCK_BOOT_BITS_EXIST is defined then two lock bits are available to set the locking mode for the Boot Loader Section (which is used in the XMEGA family).</p>
|
|
<p>The AVR lockbit modes have inverted values, logical 1 for an unprogrammed (disabled) bit and logical 0 for a programmed (enabled) bit. The defined macros for each individual lock bit represent this in their definition by a bit-wise inversion of a mask. For example, the LB_MODE_3 macro is defined as: </p>
|
|
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #define LB_MODE_3 (0xFC)</span>
|
|
<span class="preprocessor">` </span>
|
|
</pre></div><p>To combine the lockbit mode macros together to represent a whole byte, use the bitwise AND operator, like so: </p>
|
|
<div class="fragment"><pre class="fragment"> (LB_MODE_3 & BLB0_MODE_2)
|
|
</pre></div><p><<a class="el" href="lock_8h.html">avr/lock.h</a>> also defines a macro that provides a default lockbit value: LOCKBITS_DEFAULT which is defined to be 0xFF.</p>
|
|
<p>See the AVR device specific datasheet for more details about these lock bits and the available mode settings.</p>
|
|
<p>A convenience macro, LOCKMEM, is defined as a GCC attribute for a custom-named section of ".lock".</p>
|
|
<p>A convenience macro, LOCKBITS, is defined that declares a variable, __lock, of type unsigned char with the attribute defined by LOCKMEM. This variable allows the end user to easily set the lockbit data.</p>
|
|
<dl class="note"><dt><b>Note:</b></dt><dd>If a device-specific I/O header file has previously defined LOCKMEM, then LOCKMEM is not redefined. If a device-specific I/O header file has previously defined LOCKBITS, then LOCKBITS is not redefined. LOCKBITS is currently known to be defined in the I/O header files for the XMEGA devices.</dd></dl>
|
|
<dl class="user"><dt><b>API Usage Example</b></dt><dd></dd></dl>
|
|
<p>Putting all of this together is easy:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include <<a class="code" href="io_8h.html">avr/io.h</a>></span>
|
|
|
|
LOCKBITS = (LB_MODE_1 & BLB0_MODE_3 & BLB1_MODE_4);
|
|
|
|
<span class="keywordtype">int</span> main(<span class="keywordtype">void</span>)
|
|
{
|
|
<span class="keywordflow">return</span> 0;
|
|
}
|
|
</pre></div><p>Or:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include <<a class="code" href="io_8h.html">avr/io.h</a>></span>
|
|
|
|
<span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> __lock <a class="code" href="group__avr__watchdog.html#gadaa6dd28b5d08df35e49b1248d7e5fb0">__attribute__</a>((section (<span class="stringliteral">".lock"</span>))) =
|
|
(LB_MODE_1 & BLB0_MODE_3 & BLB1_MODE_4);
|
|
|
|
<span class="keywordtype">int</span> main(<span class="keywordtype">void</span>)
|
|
{
|
|
<span class="keywordflow">return</span> 0;
|
|
}
|
|
</pre></div><p>However there are a number of caveats that you need to be aware of to use this API properly.</p>
|
|
<p>Be sure to include <<a class="el" href="io_8h.html">avr/io.h</a>> to get all of the definitions for the API. The LOCKBITS macro defines a global variable to store the lockbit data. This variable is assigned to its own linker section. Assign the desired lockbit values immediately in the variable initialization.</p>
|
|
<p>The .lock section in the ELF file will get its values from the initial variable assignment ONLY. This means that you can NOT assign values to this variable in functions and the new values will not be put into the ELF .lock section.</p>
|
|
<p>The global variable is declared in the LOCKBITS macro has two leading underscores, which means that it is reserved for the "implementation", meaning the library, so it will not conflict with a user-named variable.</p>
|
|
<p>You must initialize the lockbit variable to some meaningful value, even if it is the default value. This is because the lockbits default to a logical 1, meaning unprogrammed. Normal uninitialized data defaults to all locgial zeros. So it is vital that all lockbits are initialized, even with default data. If they are not, then the lockbits may not programmed to the desired settings and can possibly put your device into an unrecoverable state.</p>
|
|
<p>Be sure to have the -mmcu=<em>device</em> flag in your compile command line and your linker command line to have the correct device selected and to have the correct I/O header file included when you include <<a class="el" href="io_8h.html">avr/io.h</a>>.</p>
|
|
<p>You can print out the contents of the .lock section in the ELF file by using this command line: </p>
|
|
<div class="fragment"><pre class="fragment"> avr-objdump -s -j .lock <ELF file>
|
|
</pre></div> </div>
|
|
<!--- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Defines</a></div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<iframe src="" frameborder="0"
|
|
name="MSearchResults" id="MSearchResults">
|
|
</iframe>
|
|
</div>
|
|
|
|
<!-- HTML footer for doxygen 1.8.7-->
|
|
<!-- start footer part -->
|
|
<!--BEGIN GENERATE_TREEVIEW-->
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
|
<ul>
|
|
$navpath
|
|
<li class="footer">$generatedby
|
|
<a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> 1.6.3 </li>
|
|
</ul>
|
|
</div>
|
|
<!--END GENERATE_TREEVIEW-->
|
|
<!--BEGIN !GENERATE_TREEVIEW-->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
$generatedby  <a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/>
|
|
</a> 1.6.3
|
|
</small></address>
|
|
<!--END !GENERATE_TREEVIEW-->
|
|
</body>
|
|
</html>
|