index.html 115 KB
Newer Older
Philippe Gerum's avatar
Philippe Gerum committed
1 2 3 4 5 6 7
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.6.8" />
<title>Migrating from Xenomai 2.x to 3.x</title>
Philippe Gerum's avatar
Philippe Gerum committed
8 9
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
Philippe Gerum's avatar
Philippe Gerum committed
10

Philippe Gerum's avatar
Philippe Gerum committed
11 12 13 14
/* Default font. */
body {
  font-family: Georgia,serif;
}
Philippe Gerum's avatar
Philippe Gerum committed
15

Philippe Gerum's avatar
Philippe Gerum committed
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536
/* Title font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
#toctitle,
#author, #revnumber, #revdate, #revremark,
#footer {
  font-family: Arial,Helvetica,sans-serif;
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}
h5 {
  font-size: 1.0em;
}

div.sectionbody {
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}
ul > li     { color: #aaa; }
ul > li > * { color: black; }

.monospaced, code, pre {
  font-family: "Courier New", Courier, monospace;
  font-size: inherit;
  color: navy;
  padding: 0;
  margin: 0;
}


#author {
  color: #527bbd;
  font-weight: bold;
  font-size: 1.1em;
}
#email {
}
#revnumber, #revdate, #revremark {
}

#footer {
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid #dddddd;
  border-left: 4px solid #f0f0f0;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid #dddddd;
  border-left: 5px solid #f0f0f0;
  background: #f8f8f8;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #f0f0f0;
  color: #888;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > pre.content {
  font-family: inherit;
  font-size: inherit;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}

div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}

div.colist td {
  padding-right: 0.5em;
  padding-bottom: 0.3em;
  vertical-align: top;
}
div.colist td img {
  margin-top: 0.3em;
}

@media print {
  #footer-badges { display: none; }
}

#toc {
  margin-bottom: 2.5em;
}

#toctitle {
  color: #527bbd;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}

span.aqua { color: aqua; }
span.black { color: black; }
span.blue { color: blue; }
span.fuchsia { color: fuchsia; }
span.gray { color: gray; }
span.green { color: green; }
span.lime { color: lime; }
span.maroon { color: maroon; }
span.navy { color: navy; }
span.olive { color: olive; }
span.purple { color: purple; }
span.red { color: red; }
span.silver { color: silver; }
span.teal { color: teal; }
span.white { color: white; }
span.yellow { color: yellow; }

span.aqua-background { background: aqua; }
span.black-background { background: black; }
span.blue-background { background: blue; }
span.fuchsia-background { background: fuchsia; }
span.gray-background { background: gray; }
span.green-background { background: green; }
span.lime-background { background: lime; }
span.maroon-background { background: maroon; }
span.navy-background { background: navy; }
span.olive-background { background: olive; }
span.purple-background { background: purple; }
span.red-background { background: red; }
span.silver-background { background: silver; }
span.teal-background { background: teal; }
span.white-background { background: white; }
span.yellow-background { background: yellow; }

span.big { font-size: 2em; }
span.small { font-size: 0.6em; }

span.underline { text-decoration: underline; }
span.overline { text-decoration: overline; }
span.line-through { text-decoration: line-through; }

div.unbreakable { page-break-inside: avoid; }


/*
 * xhtml11 specific
 *
 * */

div.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-weight: bold;
  color: #527bbd;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


/*
 * html5 specific
 *
 * */

table.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
thead, p.tableblock.header {
  font-weight: bold;
  color: #527bbd;
}
p.tableblock {
  margin-top: 0;
}
table.tableblock {
  border-width: 3px;
  border-spacing: 0px;
  border-style: solid;
  border-color: #527bbd;
  border-collapse: collapse;
}
th.tableblock, td.tableblock {
  border-width: 1px;
  padding: 4px;
  border-style: solid;
  border-color: #527bbd;
}

table.tableblock.frame-topbot {
  border-left-style: hidden;
  border-right-style: hidden;
}
table.tableblock.frame-sides {
  border-top-style: hidden;
  border-bottom-style: hidden;
}
table.tableblock.frame-none {
  border-style: hidden;
}

th.tableblock.halign-left, td.tableblock.halign-left {
  text-align: left;
}
th.tableblock.halign-center, td.tableblock.halign-center {
  text-align: center;
}
th.tableblock.halign-right, td.tableblock.halign-right {
  text-align: right;
}

th.tableblock.valign-top, td.tableblock.valign-top {
  vertical-align: top;
}
th.tableblock.valign-middle, td.tableblock.valign-middle {
  vertical-align: middle;
}
th.tableblock.valign-bottom, td.tableblock.valign-bottom {
  vertical-align: bottom;
}


/*
 * manpage specific
 *
 * */

body.manpage h1 {
  padding-top: 0.5em;
  padding-bottom: 0.5em;
  border-top: 2px solid silver;
  border-bottom: 2px solid silver;
}
body.manpage h2 {
  border-style: none;
}
body.manpage div.sectionbody {
  margin-left: 3em;
}

@media print {
  body.manpage div#toc { display: none; }
}


</style>
Philippe Gerum's avatar
Philippe Gerum committed
537 538
<script type="text/javascript">
/*<![CDATA[*/
Philippe Gerum's avatar
Philippe Gerum committed
539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727
var asciidoc = {  // Namespace.

/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////

/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, 2006, 2009. License: GPL */

// toclevels = 1..4.
toc: function (toclevels) {

  function getText(el) {
    var text = "";
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
        text += i.data;
      else if (i.firstChild != null)
        text += getText(i);
    }
    return text;
  }

  function TocEntry(el, text, toclevel) {
    this.element = el;
    this.text = text;
    this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
    var result = new Array;
    var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
    // Function that scans the DOM tree for header elements (the DOM2
    // nodeIterator API would be a better technique but not supported by all
    // browsers).
    var iterate = function (el) {
      for (var i = el.firstChild; i != null; i = i.nextSibling) {
        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
          var mo = re.exec(i.tagName);
          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
          }
          iterate(i);
        }
      }
    }
    iterate(el);
    return result;
  }

  var toc = document.getElementById("toc");
  if (!toc) {
    return;
  }

  // Delete existing TOC entries in case we're reloading the TOC.
  var tocEntriesToRemove = [];
  var i;
  for (i = 0; i < toc.childNodes.length; i++) {
    var entry = toc.childNodes[i];
    if (entry.nodeName.toLowerCase() == 'div'
     && entry.getAttribute("class")
     && entry.getAttribute("class").match(/^toclevel/))
      tocEntriesToRemove.push(entry);
  }
  for (i = 0; i < tocEntriesToRemove.length; i++) {
    toc.removeChild(tocEntriesToRemove[i]);
  }

  // Rebuild TOC entries.
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "_toc_" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    toc.parentNode.removeChild(toc);
},


/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////

/* Based on footnote generation code from:
 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 */

footnotes: function () {
  // Delete existing footnote entries in case we're reloading the footnodes.
  var i;
  var noteholder = document.getElementById("footnotes");
  if (!noteholder) {
    return;
  }
  var entriesToRemove = [];
  for (i = 0; i < noteholder.childNodes.length; i++) {
    var entry = noteholder.childNodes[i];
    if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
      entriesToRemove.push(entry);
  }
  for (i = 0; i < entriesToRemove.length; i++) {
    noteholder.removeChild(entriesToRemove[i]);
  }

  // Rebuild footnote entries.
  var cont = document.getElementById("content");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
    if (spans[i].className == "footnote") {
      n++;
      var note = spans[i].getAttribute("data-note");
      if (!note) {
        // Use [\s\S] in place of . so multi-line matches work.
        // Because JavaScript has no s (dotall) regex flag.
        note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
        spans[i].innerHTML =
          "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
        spans[i].setAttribute("data-note", note);
      }
      noteholder.innerHTML +=
        "<div class='footnote' id='_footnote_" + n + "'>" +
        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
        n + "</a>. " + note + "</div>";
      var id =spans[i].getAttribute("id");
      if (id != null) refs["#"+id] = n;
    }
  }
  if (n == 0)
    noteholder.parentNode.removeChild(noteholder);
  else {
    // Process footnoterefs.
    for (i=0; i<spans.length; i++) {
      if (spans[i].className == "footnoteref") {
        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
        href = href.match(/#.*/)[0];  // Because IE return full URL.
        n = refs[href];
        spans[i].innerHTML =
          "[<a href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
      }
    }
  }
},

install: function(toclevels) {
  var timerId;

  function reinstall() {
    asciidoc.footnotes();
    if (toclevels) {
      asciidoc.toc(toclevels);
    }
  }

  function reinstallAndRemoveTimer() {
    clearInterval(timerId);
    reinstall();
  }

  timerId = setInterval(reinstall, 500);
  if (document.addEventListener)
    document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
  else
    window.onload = reinstallAndRemoveTimer;
}

}
Philippe Gerum's avatar
Philippe Gerum committed
728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743
asciidoc.install(3);
/*]]>*/
</script>
</head>
<body class="article" style="max-width:55em">
<div id="header">
<h1>Migrating from Xenomai 2.x to 3.x</h1>
<div id="toc">
  <div id="toctitle">Table of Contents</div>
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="_configuration">1. Configuration</h2>
<div class="sectionbody">
Philippe Gerum's avatar
Philippe Gerum committed
744 745
<div class="sect2">
<h3 id="_user_programs_and_libraries">1.1. User programs and libraries</h3>
Philippe Gerum's avatar
Philippe Gerum committed
746 747 748 749 750
<div class="dlist"><dl>
<dt class="hdlist1">
Changes in <code>xeno-config</code>
</dt>
<dd>
Philippe Gerum's avatar
Philippe Gerum committed
751 752 753 754 755 756 757 758 759 760
<p>
As with Xenomai 2.x, <code>xeno-config</code> is available for retrieving the
compilation and link flags for building Xenomai 3.x applications. This
script will work for both the Cobalt and Mercury environments
indifferently.
</p>
<div class="ulist"><ul>
<li>
<p>
Each <code>--skin=&lt;api&gt;</code> option specifier can be abbreviated as
Philippe Gerum's avatar
Philippe Gerum committed
761
 <code>--&lt;api&gt;</code>. For instance, <code>--psos</code> is a shorthand for <code>--skin=psos</code> on
Philippe Gerum's avatar
Philippe Gerum committed
762 763 764 765 766
 the command line.
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783
Over Cobalt, only <strong>xeno-config --posix --ldflags</strong> (or <strong>--rtdm</strong> as
 an alias) returns the proper linker flags to cause POSIX routines
 invoked by the application to be wrapped to their respective Xenomai
 implementation. No other API will imply such wrapping. For this
 reason, <strong>--cobalt --ldflags</strong> should be used for linking exclusively
 against the Cobalt library (i.e. <code>libcobalt.so</code>) <strong>without</strong> symbol
 wrapping. Conversely, mentioning <strong>--posix</strong> along with other API
 switches with <strong>--ldflags</strong> will cause POSIX symbol wrapping to take
 place, e.g. use <strong>--posix --alchemy --ldflags</strong> for mixed API support
 with POSIX symbol wrapping.
</p>
</li>
<li>
<p>
Over <em>Mercury</em>, <code>--posix</code> and <code>--rtdm</code> are ignored placeholders,
   since the full POSIX API is available with the glibc and the
   threading library.
Philippe Gerum's avatar
Philippe Gerum committed
784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799
</p>
</li>
<li>
<p>
<code>--[skin=]alchemy</code> replaces the former <code>--skin=native</code> switch.
</p>
</li>
<li>
<p>
<code>--core</code> can be used to retrieve the name of the Xenomai core system
  for which <code>xeno-config</code> was generated. Possible output values are
  <code>cobalt</code> and <code>mercury</code>.
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
800 801 802 803 804 805
<code>--ccld</code> retrieves a C compiler command suitable for linking a
   Xenomai 3.x application.
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
806 807
<code>--info</code> retrieves the current system information, including the
   Xenomai release detected on the platform.
Philippe Gerum's avatar
Philippe Gerum committed
808 809 810
</p>
</li>
</ul></div>
Philippe Gerum's avatar
Philippe Gerum committed
811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857
</dd>
<dt class="hdlist1">
Auto-initialization
</dt>
<dd>
<p>
<code>--no-auto-init</code> can be passed to disable automatic initialization of
the Copperplate library when the application process enters the
<code>main()</code> routine.
</p>
</dd>
</dl></div>
<div class="paragraph" id="auto-init"><p>In such a case, the application code using any API based on the
Copperplate layer, shall call the <code>copperplate_init(int *argcp, char
*const **argvp)</code> routine manually, as part of its initialization
process, <em>before</em> any real-time service is invoked.</p></div>
<div class="paragraph"><p>This routine takes the addresses of the argument count and vector
passed to the main() routine respectively. copperplate_init() handles
the Xenomai options present in the argument vector, stripping them
out, leaving only unprocessed options on return in the vector,
updating the count accordingly.</p></div>
<div class="paragraph"><p><code>xeno-config</code> enables the Copperplate auto-init feature by default.</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
x86 vsyscall support
</dt>
<dd>
<p>
The <code>--enable-x86-sep</code> configuration switch was renamed to
<code>--enable-x86-vsyscall</code> to fix a misnomer. This option should be left
enabled (default), unless <strong>linuxthreads</strong> are used instead of <strong>NPTL</strong>.
</p>
</dd>
</dl></div>
</div>
<div class="sect2">
<h3 id="_kernel_parameters_cobalt">1.2. Kernel parameters (Cobalt)</h3>
<div class="dlist"><dl>
<dt class="hdlist1">
System parameters renamed
</dt>
<dd>
<div class="ulist"><ul>
<li>
<p>
xeno_hal.supported_cpus &#8594; xenomai.supported_cpus
</p>
Philippe Gerum's avatar
Philippe Gerum committed
858 859 860
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
861
xeno_hal.clockfreq &#8594; xenomai.clockfreq
Philippe Gerum's avatar
Philippe Gerum committed
862 863 864 865
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
866
xeno_hal.disable &#8594; xenomai.state=disabled
Philippe Gerum's avatar
Philippe Gerum committed
867 868 869 870 871 872 873 874 875 876 877 878 879 880 881
</p>
</li>
<li>
<p>
xeno_hal.timerfreq &#8594; xenomai.timerfreq
</p>
</li>
<li>
<p>
xeno_hal.cpufreq &#8594; xenomai.cpufreq
</p>
</li>
<li>
<p>
xeno_nucleus.watchdog_timeout &#8594; xenomai.watchdog_timeout
Philippe Gerum's avatar
Philippe Gerum committed
882 883 884 885
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
886 887 888 889 890 891 892 893 894 895
xeno_nucleus.xenomai_gid &#8594; xenomai.allowed_group
</p>
</li>
<li>
<p>
xeno_nucleus.sysheap_size &#8594; xenomai.sysheap_size
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
896
xeno_hal.smi (x86 only) &#8594; xenomai.smi
Philippe Gerum's avatar
Philippe Gerum committed
897 898 899 900
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
901
xeno_hal.smi_mask (x86 only) &#8594; xenomai.smi_mask
Philippe Gerum's avatar
Philippe Gerum committed
902 903 904
</p>
</li>
</ul></div>
Philippe Gerum's avatar
Philippe Gerum committed
905 906 907 908 909
</dd>
<dt class="hdlist1">
Obsolete parameters dropped
</dt>
<dd>
Philippe Gerum's avatar
Philippe Gerum committed
910 911
<div class="ulist"><ul>
<li>
Philippe Gerum's avatar
Philippe Gerum committed
912 913
<p>
xeno_rtdm.tick_arg
Philippe Gerum's avatar
Philippe Gerum committed
914 915 916 917
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
918
rtdm.devname_hashtab_size
Philippe Gerum's avatar
Philippe Gerum committed
919 920 921 922
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
923 924
rtdm.protocol_hashtab_size
</p>
Philippe Gerum's avatar
Philippe Gerum committed
925 926
</li>
</ul></div>
Philippe Gerum's avatar
Philippe Gerum committed
927 928
</dd>
</dl></div>
Philippe Gerum's avatar
Philippe Gerum committed
929 930
<div class="sidebarblock">
<div class="content">
Philippe Gerum's avatar
Philippe Gerum committed
931
<div class="title">Rationale</div>
Philippe Gerum's avatar
Philippe Gerum committed
932 933 934 935
<div class="paragraph"><p>Periodic timing is directly handled from the API layer in
user-space. Cobalt kernel timing is tickless.</p></div>
</div></div>
</div>
Philippe Gerum's avatar
Philippe Gerum committed
936 937 938 939 940
</div>
</div>
<div class="sect1">
<h2 id="_getting_the_system_state">2. Getting the system state</h2>
<div class="sectionbody">
Philippe Gerum's avatar
Philippe Gerum committed
941 942
<div class="paragraph"><p>When running Copperplate-based APIs (i.e. all but pure POSIX),
querying the state of the real-time system should be done via the new
Philippe Gerum's avatar
Philippe Gerum committed
943 944 945 946 947 948 949 950 951 952 953 954 955
Xenomai registery interface available with Xenomai 3.x, which is
turned on when <code>--enable-registry</code> is passed to the configuration
script for building the Xenomai libraries and programs.</p></div>
<div class="paragraph"><p>The new registry support is common to the Cobalt and Mercury cores,
with only marginal differences due to the presence (or lack of) co-
kernel in the system.</p></div>
<div class="sect2">
<h3 id="_new_fuse_based_registry_interface">2.1. New FUSE-based registry interface</h3>
<div class="paragraph"><p>The Xenomai system state is now fully exported via a FUSE-based
filesystem.  The hierarchy of the Xenomai registry is organized as
follows:</p></div>
<div class="listingblock">
<div class="content">
Philippe Gerum's avatar
Philippe Gerum committed
956
<pre><code>/mount-point              /* registry fs root, defaults to /var/run/xenomai */
Philippe Gerum's avatar
Philippe Gerum committed
957 958
 /user                    /* user name */
    /session              /* shared session name or anon@&lt;pid&gt; */
Philippe Gerum's avatar
Philippe Gerum committed
959 960 961 962 963
      /pid                /* application (main) pid */
        /skin             /* API name: alchemy/vxworks/psos/... */
          /family         /* object class (task, semaphore, ...) */
             { exported objects... }
      /system             /* session-wide information */</code></pre>
Philippe Gerum's avatar
Philippe Gerum committed
964 965 966 967
</div></div>
<div class="paragraph"><p>Each leaf entry under a session hierarchy is normally viewable, for
retrieving the information attached to the corresponding object, such
as its state, and/or value. There can be multiple sessions hosted
Philippe Gerum's avatar
Philippe Gerum committed
968
under a single registry mount point.</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
969 970 971 972 973 974 975 976 977 978 979
<div class="paragraph"><p>The /system hierarchy provides information about the current state of
the Xenomai core, aggregating data from all processes which belong to
the parent session. Typically, the status of all threads and heaps
created by the session can be retrieved.</p></div>
<div class="paragraph"><p>The registry daemon is a companion tool managing exactly one registry
mount point, which is specified by the --root option on the command
line. This daemon is automatically spawned by the registry support
code as required. There is normally no action required from users for
managing it.</p></div>
</div>
<div class="sect2">
Philippe Gerum's avatar
Philippe Gerum committed
980 981 982 983 984 985
<h3 id="_proc_xenomai_interface">2.2. /proc/xenomai interface</h3>
<div class="paragraph"><p>The /proc/xenomai interface is still available when running over the
Cobalt core, mainly for pure POSIX-based applications. The following
changes took place:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
Philippe Gerum's avatar
Philippe Gerum committed
986
Thread status
Philippe Gerum's avatar
Philippe Gerum committed
987 988 989 990 991
</dt>
<dd>
<p>
All pseudo-files reporting the various thread states moved under the
new <code>sched/</code> hierarchy, i.e.
Philippe Gerum's avatar
Philippe Gerum committed
992
</p>
Philippe Gerum's avatar
Philippe Gerum committed
993 994
</dd>
</dl></div>
Philippe Gerum's avatar
Philippe Gerum committed
995
<div class="paragraph"><p><code>{sched, stat, acct}</code> &#8594; <code>sched/{threads, stat, acct}</code></p></div>
Philippe Gerum's avatar
Philippe Gerum committed
996 997
<div class="dlist"><dl>
<dt class="hdlist1">
Philippe Gerum's avatar
Philippe Gerum committed
998
Clocks
Philippe Gerum's avatar
Philippe Gerum committed
999 1000 1001 1002
</dt>
<dd>
<p>
With the introduction of dynamic clock registration in the Cobalt
Philippe Gerum's avatar
Philippe Gerum committed
1003
core, the <code>clock/</code> hierarchy was added, to reflect the current state
Philippe Gerum's avatar
Philippe Gerum committed
1004 1005 1006 1007
of all timers from the registered Xenomai clocks.
</p>
</dd>
</dl></div>
Philippe Gerum's avatar
Philippe Gerum committed
1008
<div class="paragraph"><p>There is no kernel-based time base management anymore with Xenomai
Philippe Gerum's avatar
Philippe Gerum committed
1009
3.0.4. Functionally speaking, only the former <em>master</em> time base
Philippe Gerum's avatar
Philippe Gerum committed
1010 1011
remains, periodic timing is now controlled locally from the Xenomai
libraries in user-space.</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
1012
<div class="paragraph"><p>Xenomai 3.0.4 defines a built-in clock named <em>coreclk</em>, which has
Philippe Gerum's avatar
Philippe Gerum committed
1013 1014
the same properties than the former <em>master</em> time base available with
Xenomai 2.x (i.e. tickless with nanosecond resolution).</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
1015 1016
<div class="paragraph"><p>The settings of existing clocks can be read from entries under the new
clock/ hierarchy. Active timers for each clock can be read from
Philippe Gerum's avatar
Philippe Gerum committed
1017
entries under the new <code>timer/</code> hierarchy.</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
1018
<div class="paragraph"><p>As a consequence of these changes:</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
1019 1020 1021
<div class="ulist"><ul>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1022 1023 1024 1025 1026 1027 1028
the information previously available from the <code>timer</code> entry is now
obtained by reading <code>clock/coreclk</code>.
</p>
</li>
<li>
<p>
the information previously available from <code>timerstat/master</code> is now
Philippe Gerum's avatar
Philippe Gerum committed
1029
obtained by reading <code>timer/coreclk</code>.
Philippe Gerum's avatar
Philippe Gerum committed
1030 1031 1032
</p>
</li>
</ul></div>
Philippe Gerum's avatar
Philippe Gerum committed
1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047
<div class="dlist"><dl>
<dt class="hdlist1">
Core clock gravity
</dt>
<dd>
<p>
The gravity value for a Xenomai clock gives the amount of time by
which the next timer shot should be anticipated. This is a static
adjustment value, to account for the basic latency of the target
system for responding to external events. Such latency may be
introduced by hardware effects (e.g. bus or cache latency), or
software issues (e.g. code running with interrupts disabled).
</p>
</dd>
</dl></div>
Philippe Gerum's avatar
Philippe Gerum committed
1048
<div class="paragraph"><p>The clock gravity management departs from Xenomai 2.x as follows:</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
1049 1050 1051
<div class="ulist"><ul>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1052 1053 1054 1055 1056 1057 1058 1059 1060
different gravity values are applied, depending on which context a
  timer activates. This may be a real-time IRQ handler (<em>irq</em>), a RTDM
  driver task (<em>kernel</em>), or a Xenomai application thread running in
  user-space (<em>user</em>). Xenomai 2.x does not differentiate, only
  applying a global gravity value regardless of the activated context.
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1061 1062
in addition to the legacy <code>latency</code> file which now reports
  the <em>user</em> timer gravity (in nanoseconds), i.e. used for timers
Philippe Gerum's avatar
Philippe Gerum committed
1063 1064
  activating user-space threads, the full gravity triplet applied to
  timers running on the core clock can be accessed by reading
Philippe Gerum's avatar
Philippe Gerum committed
1065
  <code>clock/coreclk</code> (also in nanoseconds).
Philippe Gerum's avatar
Philippe Gerum committed
1066 1067 1068 1069 1070
</p>
</li>
<li>
<p>
at reset, the <em>user</em> gravity for the core clock now represents the
Philippe Gerum's avatar
Philippe Gerum committed
1071 1072 1073 1074
sum of the scheduling <strong>and</strong> hardware timer reprogramming time as a
count of nanoseconds. This departs from Xenomai 2.x for which only the
former was accounted for as a global gravity value, regardless of the
target context for the timer.
Philippe Gerum's avatar
Philippe Gerum committed
1075 1076
</p>
</li>
Philippe Gerum's avatar
Philippe Gerum committed
1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099
</ul></div>
<div class="paragraph"><p>The following command reports the current gravity triplet for the
target system, along with the setup information for the core timer:</p></div>
<div class="listingblock">
<div class="content">
<pre><code># cat xenomai/clock/coreclk
gravity: irq=848 kernel=8272 user=35303
devices: timer=decrementer, clock=timebase
 status: on+watchdog
  setup: 151
  ticks: 220862243033</code></pre>
</div></div>
<div class="paragraph"><p>Conversely, writing to this file manually changes the gravity values
of the Xenomai core clock:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>    /* change the user gravity (default) */
# echo 3000 &gt; /proc/xenomai/clock/coreclck
    /* change the IRQ gravity */
# echo 1000i &gt; /proc/xenomai/clock/coreclck
    /* change the user and kernel gravities */
# echo "2000u 1000k" &gt; /proc/xenomai/clock/coreclck</code></pre>
</div></div>
Philippe Gerum's avatar
Philippe Gerum committed
1100 1101 1102 1103 1104
<div class="dlist"><dl>
<dt class="hdlist1">
<code>interfaces</code> removed
</dt>
<dd>
Philippe Gerum's avatar
Philippe Gerum committed
1105
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1106
Only the POSIX and RTDM APIs remain implemented directly in kernel
Philippe Gerum's avatar
Philippe Gerum committed
1107 1108
space, and are always present when the Cobalt core enabled in the
configuration. All other APIs are implemented in user-space over the
Philippe Gerum's avatar
Philippe Gerum committed
1109 1110
Copperplate layer. This makes the former <code>interfaces</code> contents
basically useless, since the corresponding information for the
Philippe Gerum's avatar
Philippe Gerum committed
1111
POSIX/RTDM interfaces can be obtained via <code>sched/threads</code>
Philippe Gerum's avatar
Philippe Gerum committed
1112 1113 1114 1115
unconditionally.
</p>
</dd>
<dt class="hdlist1">
Philippe Gerum's avatar
Philippe Gerum committed
1116
<code>registry/usage</code> changed format
Philippe Gerum's avatar
Philippe Gerum committed
1117 1118 1119 1120
</dt>
<dd>
<p>
The new print out is &lt;used slot count&gt;/&lt;total slot count&gt;.
Philippe Gerum's avatar
Philippe Gerum committed
1121
</p>
Philippe Gerum's avatar
Philippe Gerum committed
1122 1123
</dd>
</dl></div>
Philippe Gerum's avatar
Philippe Gerum committed
1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155
</div>
</div>
</div>
<div class="sect1">
<h2 id="_binary_object_features">3. Binary object features</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_loading_xenomai_libraries_dynamically">3.1. Loading Xenomai libraries dynamically</h3>
<div class="paragraph"><p>The new <code>--enable-dlopen-libs</code> configuration switch must be turned on
to allow Xenomai libaries to be dynamically loaded via dlopen(3).</p></div>
<div class="paragraph"><p>This replaces the former <code>--enable-dlopen-skins</code> switch. Unlike the
latter, <code>--enable-dlopen-libs</code> does not implicitly disable support for
thread local storage, but rather selects a suitable TLS model
(i.e. <em>global-dynamic</em>).</p></div>
</div>
<div class="sect2">
<h3 id="_thread_local_storage">3.2. Thread local storage</h3>
<div class="paragraph"><p>The former <code>--with-__thread</code> configuration switch was renamed
<code>--enable-tls</code>.</p></div>
<div class="paragraph"><p>As mentioned earlier, TLS is now available to dynamically loaded
Xenomai libraries, e.g. <code>--enable-tls --enable-dlopen-libs</code> on a
configuration line is valid. This would select the <em>global-dynamic</em>
TLS model instead of <em>initial-exec</em>, to make sure all thread-local
variables may be accessed from any code module.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_process_level_management">4. Process-level management</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_main_thread_shadowing">4.1. Main thread shadowing</h3>
Philippe Gerum's avatar
Philippe Gerum committed
1156 1157 1158 1159 1160
<div class="paragraph"><p>Any application linked against <code>libcobalt</code> has its main thread
attached to the real-time system automatically, this operation is
called <em>auto-shadowing</em>. As a side-effect, the entire process&#8217;s memory
is locked, for current and future mappings
(i.e. <code>mlockall(MCL_CURRENT|MCL_FUTURE)</code>).</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201
</div>
<div class="sect2">
<h3 id="_shadow_signal_handler">4.2. Shadow signal handler</h3>
<div class="paragraph"><p>Xenomai&#8217;s <code>libcobalt</code> installs a handler for the SIGWINCH (aka
<em>SIGSHADOW</em>) signal. This signal may be sent by the Cobalt core to any
real-time application, for handling internal duties.</p></div>
<div class="paragraph"><p>Applications are allowed to interpose on the SIGSHADOW handler,
provided they first forward all signal notifications to this routine,
then eventually handle all events the Xenomai handler won&#8217;t process.</p></div>
<div class="paragraph"><p>This handler was renamed from <code>xeno_sigwinch_handler()</code> (Xenomai 2.x)
to <code>cobalt_sigshadow_handler()</code> in Xenomai 3.x. The function prototype
did not change though, i.e.:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>int cobalt_sigshadow_handler(int sig, siginfo_t *si, void *ctxt)</code></pre>
</div></div>
<div class="paragraph"><p>A non-zero value is returned whenever the event was handled internally
by the Xenomai system.</p></div>
</div>
<div class="sect2">
<h3 id="_debug_signal_handler">4.3. Debug signal handler</h3>
<div class="paragraph"><p>Xenomai&#8217;s <code>libcobalt</code> installs a handler for the SIGXCPU (aka
<em>SIGDEBUG</em>) signal. This signal may be sent by the Cobalt core to any
real-time application, for notifying various debug events.</p></div>
<div class="paragraph"><p>Applications are allowed to interpose on the SIGDEBUG handler,
provided they eventually forward all signal notifications they won&#8217;t
process to the Xenomai handler.</p></div>
<div class="paragraph"><p>This handler was renamed from <code>xeno_handle_mlock_alert()</code> (Xenomai
2.x) to <code>cobalt_sigdebug_handler()</code> in Xenomai 3.x. The function
prototype did not change though, i.e.:</p></div>
<div class="paragraph"><p><code>void cobalt_sigdebug_handler(int sig, siginfo_t *si, void *ctxt)</code></p></div>
</div>
<div class="sect2">
<h3 id="_copperplate_auto_initialization">4.4. Copperplate auto-initialization</h3>
<div class="paragraph"><p>Copperplate is a library layer which mediates between the real-time
core services available on the platform, and the API exposed to the
application. It provides typical programming abstractions for
emulating real-time APIs. All non-POSIX APIs are based on Copperplate
services (e.g. <em>alchemy</em>, <em>psos</em>, <em>vxworks</em>).</p></div>
<div class="paragraph"><p>When Copperplate is built for running over the Cobalt core, it sits on
top of the <code>libcobalt</code> library. Conversely, it is directly stacked on
Philippe Gerum's avatar
Philippe Gerum committed
1202 1203
top of the <strong>glibc</strong> or <strong>uClibc</strong> when built for running over the Mercury
core.</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
1204 1205 1206 1207 1208 1209
<div class="paragraph"><p>Normally, Copperplate should initialize from a call issued by the
<code>main()</code> application routine. To make this process transparent for the
user, the <code>xeno-config</code> script emits link flags which temporarily
overrides the <code>main()</code> routine with a Copperplate-based replacement,
running the proper initialization code as required, before branching
back to the user-defined application entry point.</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
1210 1211
<div class="paragraph"><p>This behavior may be disabled by passing the
<a href="#auto-init"><code>--no-auto-init</code></a> option.</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
1212 1213 1214 1215 1216 1217
</div>
</div>
</div>
<div class="sect1">
<h2 id="_rtdm_interface_changes">5. RTDM interface changes</h2>
<div class="sectionbody">
Philippe Gerum's avatar
Philippe Gerum committed
1218 1219 1220
<div class="sect2">
<h3 id="_files_renamed">5.1. Files renamed</h3>
<div class="ulist"><ul>
Philippe Gerum's avatar
Philippe Gerum committed
1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231
<li>
<p>
Redundant prefixes were removed from the following files:
</p>
</li>
</ul></div>
<div class="paragraph"><p>rtdm/rtdm_driver.h &#8594; rtdm/driver.h</p></div>
<div class="paragraph"><p>rtdm/rtcan.h &#8594; rtdm/can.h</p></div>
<div class="paragraph"><p>rtdm/rtserial.h &#8594; rtdm/serial.h</p></div>
<div class="paragraph"><p>rtdm/rttesting.h &#8594; rtdm/testing.h</p></div>
<div class="paragraph"><p>rtdm/rtipc.h &#8594; rtdm/ipc.h</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
1232 1233 1234
</div>
<div class="sect2">
<h3 id="_driver_api">5.2. Driver API</h3>
Philippe Gerum's avatar
Philippe Gerum committed
1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428
<div class="sect3">
<h4 id="_new_device_description_model">5.2.1. New device description model</h4>
<div class="paragraph"><p>Several changes have taken place in the device description passed to
<code>rtdm_dev_register()</code> (i.e. <code>struct rtdm_device</code>). Aside of fixing
consistency issues, the bulk of changes is aimed at narrowing the gap
between the regular Linux device driver model and RTDM.</p></div>
<div class="paragraph"><p>To this end, RTDM in Xenomai 3 shares the Linux namespace for named
devices, which are now backed by common character device objects from
the regular Linux device model. As a consequence of this, file
descriptors obtained on named RTDM devices are regular file
descriptors, visible from the <code>/proc/&lt;pid&gt;/fd</code> interface.</p></div>
<div class="sect4">
<h5 id="_named_device_description">Named device description</h5>
<div class="paragraph"><p>The major change required for supporting this closer integration of
RTDM into the regular Linux driver model involved splitting the device
driver properties from the device instance definitions, which used to
be combined in Xenomai 2.x into the <code>rtdm_device</code> descriptor.</p></div>
<div class="listingblock">
<div class="title">Xenomai 2.x named device description</div>
<div class="content">
<pre><code>static struct rtdm_device foo_device0 = {
        .struct_version         =       RTDM_DEVICE_STRUCT_VER,
        .device_flags           =       RTDM_NAMED_DEVICE|RTDM_EXCLUSIVE,
        .device_id              =       0
        .context_size           =       sizeof(struct foo_context),
        .ops = {
                .open           =       foo_open,
                .ioctl_rt       =       foo_ioctl_rt,
                .ioctl_nrt      =       foo_ioctl_nrt,
                .close          =       foo_close,
        },
        .device_class           =       RTDM_CLASS_EXPERIMENTAL,
        .device_sub_class       =       RTDM_SUBCLASS_FOO,
        .profile_version        =       42,
        .device_name            =       "foo0",
        .driver_name            =       "foo driver",
        .driver_version         =       RTDM_DRIVER_VER(1, 0, 0),
        .peripheral_name        =       "Ultra-void IV board driver",
        .proc_name              =       device.device_name,
        .provider_name          =       "Whoever",
};

static struct rtdm_device foo_device1 = {
        .struct_version         =       RTDM_DEVICE_STRUCT_VER,
        .device_flags           =       RTDM_NAMED_DEVICE|RTDM_EXCLUSIVE,
        .device_id              =       1
        .context_size           =       sizeof(struct foo_context),
        .ops = {
                .open           =       foo_open,
                .ioctl_rt       =       foo_ioctl_rt,
                .ioctl_nrt      =       foo_ioctl_nrt,
                .close          =       foo_close,
        },
        .device_class           =       RTDM_CLASS_EXPERIMENTAL,
        .device_sub_class       =       RTDM_SUBCLASS_FOO,
        .profile_version        =       42,
        .device_name            =       "foo1",
        .device_data            =       NULL,
        .driver_name            =       "foo driver",
        .driver_version         =       RTDM_DRIVER_VER(1, 0, 0),
        .peripheral_name        =       "Ultra-void IV board driver",
        .proc_name              =       device.device_name,
        .provider_name          =       "Whoever",
};

foo0.device_data = &amp;some_driver_data0;
ret = rtdm_dev_register(&amp;foo0);
...
foo1.device_data = &amp;some_driver_data1;
ret = rtdm_dev_register(&amp;foo1);</code></pre>
</div></div>
<div class="paragraph"><p>The legacy description above would only create "virtual" device
entries, private to the RTDM device namespace, with no visible
counterparts into the Linux device namespace.</p></div>
<div class="listingblock">
<div class="title">Xenomai 3.x named device description</div>
<div class="content">
<pre><code>static struct rtdm_driver foo_driver = {
        .profile_info           =       RTDM_PROFILE_INFO(foo,
                                                          RTDM_CLASS_EXPERIMENTAL,
                                                          RTDM_SUBCLASS_FOO,
                                                          42),
        .device_flags           =       RTDM_NAMED_DEVICE|RTDM_EXCLUSIVE,
        .device_count           =       2,
        .context_size           =       sizeof(struct foo_context),
        .ops = {
                .open           =       foo_open,
                .ioctl_rt       =       foo_ioctl_rt,
                .ioctl_nrt      =       foo_ioctl_nrt,
                .close          =       foo_close,
        },
};

static struct rtdm_device foo_devices[2] = {
        [ 0 ... 1 ] = {
                .driver = &amp;foo_driver,
                .label = "foo%d",
        },
};

MODULE_VERSION("1.0.0");
MODULE_DESCRIPTION("Ultra-void IV board driver");
MODULE_AUTHOR'"Whoever");

foo_devices[0].device_data = &amp;some_driver_data0;
ret = rtdm_dev_register(&amp;foo_devices[0]);
...
foo_devices[1].device_data = &amp;some_driver_data1;
ret = rtdm_dev_register(&amp;foo_devices[1]);</code></pre>
</div></div>
<div class="paragraph"><p>The current description above will cause the device nodes
/dev/rtdm/foo0 and /dev/rtdm/foo1 to be created in the Linux device
namespace. Application may open these device nodes for interacting
with the RTDM driver, as they would do with any regular <em>chrdev</em>
driver.</p></div>
</div>
<div class="sect4">
<h5 id="_protocol_device_description">Protocol device description</h5>
<div class="paragraph"><p>Similarly, the registration data for protocol devices have been
changed to follow the new generic layout:</p></div>
<div class="listingblock">
<div class="title">Xenomai 2.x protocol device description</div>
<div class="content">
<pre><code>static struct rtdm_device foo_device = {
        .struct_version =       RTDM_DEVICE_STRUCT_VER,
        .device_flags   =       RTDM_PROTOCOL_DEVICE,
        .context_size   =       sizeof(struct foo_context),
        .device_name    =       "foo",
        .protocol_family=       PF_FOO,
        .socket_type    =       SOCK_DGRAM,
        .socket_nrt     =       foo_socket,
        .ops = {
                .close_nrt      =       foo_close,
                .recvmsg_rt     =       foo_recvmsg,
                .sendmsg_rt     =       foo_sendmsg,
                .ioctl_rt       =       foo_ioctl,
                .ioctl_nrt      =       foo_ioctl,
                .read_rt        =       foo_read,
                .write_rt       =       foo_write,
                .select_bind    =       foo_select,
        },
        .device_class           =       RTDM_CLASS_EXPERIMENTAL,
        .device_sub_class       =       RTDM_SUBCLASS_FOO,
        .profile_version        =       1,
        .driver_name            =       "foo",
        .driver_version         =       RTDM_DRIVER_VER(1, 0, 0),
        .peripheral_name        =       "Unexpected protocol driver",
        .proc_name              =       device.device_name,
        .provider_name          =       "Whoever",
        .device_data            =       &amp;some_driver_data,
};

ret = rtdm_dev_register(&amp;foo_device);
...</code></pre>
</div></div>
<div class="listingblock">
<div class="title">Xenomai 3.x protocol device description</div>
<div class="content">
<pre><code>static struct rtdm_driver foo_driver = {
        .profile_info           =       RTDM_PROFILE_INFO(foo,
                                                          RTDM_CLASS_EXPERIMENTAL,
                                                          RTDM_SUBCLASS_FOO,
                                                          1),
        .device_flags           =       RTDM_PROTOCOL_DEVICE,
        .device_count           =       1,
        .context_size           =       sizeof(struct foo_context),
        .protocol_family        =       PF_FOO,
        .socket_type            =       SOCK_DGRAM,
        .ops = {
                .socket         =       foo_socket,
                .close          =       foo_close,
                .recvmsg_rt     =       foo_recvmsg,
                .sendmsg_rt     =       foo_sendmsg,
                .ioctl_rt       =       foo_ioctl,
                .ioctl_nrt      =       foo_ioctl,
                .read_rt        =       foo_read,
                .write_rt       =       foo_write,
                .select         =       foo_select,
        },
};

static struct rtdm_device foo_device = {
        .driver = &amp;foo_driver,
        .label = "foo",
        .device_data = &amp;some_driver_data,
};

ret = rtdm_dev_register(&amp;foo_device);
...

MODULE_VERSION("1.0.0");
MODULE_DESCRIPTION("Unexpected protocol driver");
MODULE_AUTHOR'"Whoever");</code></pre>
</div></div>
Philippe Gerum's avatar
Philippe Gerum committed
1429
<div class="ulist"><ul>
Philippe Gerum's avatar
Philippe Gerum committed
1430 1431
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485
<code>.device_count</code> has been added to reflect the (maximum) number of
  device instances which may be managed by the driver. This
  information is used to dynamically reserve a range of major/minor
  numbers for named RTDM devices in the Linux device namespace, by a
  particular driver.  Device minors are assigned to RTDM device
  instances in order of registration starting from minor #0, unless
  RTDM_FIXED_MINOR is present in the device flags. In the latter case,
  rtdm_device.minor is used verbatim by the RTDM core when registering
  the device.
</p>
</li>
<li>
<p>
<code>.device_id</code> was removed from the device description, as the minor
  number it was most commonly holding is now available from a call to
  rtdm_fd_minor(). Drivers should use <code>.device_data</code> for storing
  private information attached to device instances.
</p>
</li>
<li>
<p>
<code>.struct_version</code> was dropped, as it provided no additional feature
  to the standard module versioning scheme.
</p>
</li>
<li>
<p>
<code>.proc_name</code> was dropped, as it is redundant with the device
  name. Above all, using a /proc information label different from the
  actual device name is unlikely to be a good idea.
</p>
</li>
<li>
<p>
<code>.device_class</code>, <code>.device_sub_class</code> and <code>.profile_version</code> numbers
  have been grouped in a dedicated profile information descriptor
  (<code>struct rtdm_profile_info</code>), one <strong>must</strong> initialize using the
  <code>RTDM_PROFILE_INFO()</code> macro.
</p>
</li>
<li>
<p>
<code>.driver_name</code> was dropped, as it adds no value to the plain module
  name (unless the module name is deliberately obfuscated, that is).
</p>
</li>
<li>
<p>
<code>.peripheral_name</code> was dropped, as this information should be
  conveyed by MODULE_DESCRIPTION().
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1486 1487
<code>.provider_name</code> was dropped, as this information should be conveyed
  by MODULE_AUTHOR().
Philippe Gerum's avatar
Philippe Gerum committed
1488 1489 1490 1491
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1492 1493
<code>.driver_version</code> was dropped, as this information should be
  conveyed by MODULE_VERSION().
Philippe Gerum's avatar
Philippe Gerum committed
1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540
</p>
</li>
</ul></div>
</div>
</div>
<div class="sect3">
<h4 id="_introduction_of_file_descriptors">5.2.2. Introduction of file descriptors</h4>
<div class="paragraph"><p>Xenomai 3 introduces a file descriptor abstraction for RTDM
drivers. For this reason, all RTDM driver handlers and services which
used to receive a <code>user_info</code> opaque argument describing the calling
context, now receive a <code>rtdm_fd</code> pointer standing for the target file
descriptor for the operation.</p></div>
<div class="paragraph"><p>As a consequence of this:</p></div>
<div class="ulist"><ul>
<li>
<p>
The <code>rtdm_context_get/put()</code> call pair has been replaced by
  <code>rtdm_fd_get/put()</code>.
</p>
</li>
<li>
<p>
Likewise, the <code>rtdm_context_lock/unlock()</code> call pair has been
  replaced by <code>rtdm_fd_lock/unlock()</code>.
</p>
</li>
<li>
<p>
<code>rtdm_fd_to_private()</code> is available to fetch the context-private
  memory allocated by the driver for a particular RTDM file
  descriptor. Conversely, <code>rtdm_private_to_fd()</code> returns the file
  descriptor owning a particular context-private memory area.
</p>
</li>
<li>
<p>
+rtdm_fd_minor() retrieves the minor number assigned to the current
  named device instance using its file descriptor.
</p>
</li>
<li>
<p>
<code>xenomai/rtdm/open_files</code> and <code>xenomai/rtdm/fildes</code> now solely
  report file descriptors obtained using the driver-to-driver API.
  RTDM file descriptors obtained from applications appear under the
  regular /proc/&lt;pid&gt;/fd hierarchy. All RTDM file descriptors obtained
  by an application are automatically released when the latter exits.
Philippe Gerum's avatar
Philippe Gerum committed
1541 1542 1543
</p>
</li>
</ul></div>
Philippe Gerum's avatar
Philippe Gerum committed
1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../asciidoc-icons/caution.png" alt="Caution" />
</td>
<td class="content">Because RTDM file descriptors may be released and destroyed
asynchronously, rtdm_fd_get() and rtdm_fd_lock() may return -EIDRM if
a file descriptor fetched from some driver-private registry becomes
stale prior to calling these services. Typically, this may happen if
the descriptor is released from the &#8594;close() handler implemented by
the driver. Therefore, make sure to always carefully check the return
value of these services.</td>
</tr></table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../asciidoc-icons/note.png" alt="Note" />
</td>
<td class="content">Unlike Xenomai 2.x, RTDM file descriptors returned to Xenomai 3
applications fall within the regular Linux range. Each open RTDM
connection is actually mapped over a regular file descriptor, which
RTDM services from <em>libcobalt</em> recognize and handle.</td>
</tr></table>
</div>
</div>
<div class="sect3">
<h4 id="_updated_device_operation_descriptor">5.2.3. Updated device operation descriptor</h4>
<div class="paragraph"><p>As visible from the previous illustrations, a few handlers have been
moved to the device operation descriptor, some dropped, other renamed,
mainly for the sake of consistency:</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
1575 1576 1577
<div class="ulist"><ul>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1578 1579 1580 1581 1582 1583 1584 1585 1586 1587
<code>.select_bind</code> was renamed as <code>.select</code> in the device operation
  descriptor.
</p>
</li>
<li>
<p>
<code>.open_rt</code> was dropped, and <code>.open_nrt</code> renamed as <code>.open</code>.  Opening
  a named device instance always happens from secondary mode. In
  addition, the new handler is now part of the device operation
  descriptor <code>.ops</code>.
Philippe Gerum's avatar
Philippe Gerum committed
1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602
</p>
</li>
</ul></div>
<div class="sidebarblock">
<div class="content">
<div class="title">Rationale</div>
<div class="paragraph"><p>Opening a device instance most often requires allocating resources
managed by the Linux kernel (memory mappings, DMA etc), which is only
available to regular calling contexts.</p></div>
</div></div>
<div class="ulist"><ul>
<li>
<p>
Likewise, <code>.socket_rt</code> was dropped, and <code>.socket_nrt</code> renamed as
  <code>.socket</code>. Opening a protocol device instance always happens from
Philippe Gerum's avatar
Philippe Gerum committed
1603 1604
  secondary mode. In addition, the new handler is now part of the
  device operation descriptor <code>.ops</code>.
Philippe Gerum's avatar
Philippe Gerum committed
1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615
</p>
</li>
<li>
<p>
As a consequence of the previous changes, <code>.close_rt</code> was dropped,
  and <code>.close_nrt</code> renamed as <code>.close</code>. Closing a device instance
  always happens from secondary mode.
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1616 1617
.open, .socket and .close handlers have become optional in Xenomai
  3.x.
Philippe Gerum's avatar
Philippe Gerum committed
1618
</p>
Philippe Gerum's avatar
Philippe Gerum committed
1619
</li>
Philippe Gerum's avatar
Philippe Gerum committed
1620 1621
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1622 1623 1624 1625 1626 1627 1628 1629
The device operation descriptor <code>.ops</code> shows two new members, namely
  <code>.mmap</code> for handling memory mapping requests to the RTDM driver, and
  <code>get_unmapped_area</code>, mainly for supporting such memory mapping
  operations in MMU-less configurations. These handlers - named after
  the similar handlers defined in the regular file_operation
  descriptor - always operate from secondary mode on behalf of the
  calling task context, so that they may invoke regular kernel
  services safely.
Philippe Gerum's avatar
Philippe Gerum committed
1630 1631 1632
</p>
</li>
</ul></div>
Philippe Gerum's avatar
Philippe Gerum committed
1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654
<div class="admonitionblock" id="rtdm-mmap">
<table><tr>
<td class="icon">
<img src="../asciidoc-icons/note.png" alt="Note" />
</td>
<td class="content">See the documentation in the
<a href="http://xenomai.org/documentation/xenomai-3/html/xeno3prm/">Programming
Reference Manual</a> covering the device registration and operation
handlers for a complete description.</td>
</tr></table>
</div>
</div>
<div class="sect3">
<h4 id="_changes_to_rtdm_services">5.2.4. Changes to RTDM services</h4>
<div class="ulist"><ul>
<li>
<p>
rtdm_dev_unregister() loses the poll_delay argument, and its return
  value. Instead, this service waits indefinitely for all ongoing
  connection to be drop prior to unregistering the device. The new
  prototype is therefore:
</p>
Philippe Gerum's avatar
Philippe Gerum committed
1655 1656
</li>
</ul></div>
Philippe Gerum's avatar
Philippe Gerum committed
1657 1658 1659 1660
<div class="listingblock">
<div class="content">
<pre><code>void rtdm_dev_unregister(struct rtdm_device *device);</code></pre>
</div></div>
Philippe Gerum's avatar
Philippe Gerum committed
1661 1662 1663
<div class="sidebarblock">
<div class="content">
<div class="title">Rationale</div>
Philippe Gerum's avatar
Philippe Gerum committed
1664 1665 1666 1667
<div class="paragraph"><p>Drivers are most often not willing to deal with receiving a device
busy condition from a module exit routine (which is the place devices
should be unregistered from).  Drivers which really want to deal with
such condition should simply use module refcounting in their own code.</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
1668 1669 1670 1671
</div></div>
<div class="ulist"><ul>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1672 1673 1674 1675
rtdm_task_init() shall be called from secondary mode.
</p>
</li>
</ul></div>
Philippe Gerum's avatar
Philippe Gerum committed
1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724
<div class="sidebarblock">
<div class="content">
<div class="title">Rationale</div>
<div class="paragraph"><p>Since Xenomai 3, rtdm_task_init() involves creating a regular kernel
thread, which will be given real-time capabilities, such as running
under the control of the Cobalt kernel. In order to invoke standard
kernel services, rtdm_task_init() must be called from a regular Linux
kernel context.</p></div>
</div></div>
<div class="ulist"><ul>
<li>
<p>
rtdm_task_join() has been introduced to wait for termination of a
  RTDM task regardless of the caller&#8217;s execution mode, which may be
  primary or secondary. In addition, rtdm_task_join() does not need to
  poll for such event unlike rtdm_task_join_nrt().
</p>
</li>
</ul></div>
<div class="sidebarblock">
<div class="content">
<div class="title">Rationale</div>
<div class="paragraph"><p>rtdm_task_join() supersedes rtdm_task_join_nrt() feature-wise with
less usage restrictions, therefore the latter has become pointless. It
is therefore deprecated and will be phased out in the next release.</p></div>
</div></div>
<div class="ulist"><ul>
<li>
<p>
A RTDM task cannot be forcibly removed from the scheduler by another
  thread for immediate deletion. Instead, the RTDM task is notified
  about a pending cancellation request, which it should act upon when
  detected. To this end, RTDM driver tasks should call the new
  <code>rtdm_task_should_stop()</code> service to detect such notification from
  their work loop, and exit accordingly.
</p>
</li>
</ul></div>
<div class="sidebarblock">
<div class="content">
<div class="title">Rationale</div>
<div class="paragraph"><p>Since Xenomai 3, a RTDM task is based on a regular kernel thread with
real-time capabilities when controlled by the Cobalt kernel. The Linux
kernel requires kernel threads to exit at their earliest convenience
upon notification, which therefore applies to RTDM tasks as well.</p></div>
</div></div>
<div class="ulist"><ul>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741
<code>rtdm_task_set_period()</code> now accepts a start date for the periodic
timeline. Zero can be passed to emulate the previous call form,
setting the first release point when the first period after the
current date elapses.
</p>
</li>
<li>
<p>
<code>rtdm_task_wait_period()</code> now copies back the count of overruns into
a user-provided variable if -ETIMEDOUT is returned. NULL can be passed
to emulate the previous call form, discarding this information.
</p>
</li>
<li>
<p>
Both <code>rtdm_task_set_period()</code> and <code>rtdm_task_wait_period()</code> may be
  invoked over a Cobalt thread context.
Philippe Gerum's avatar
Philippe Gerum committed
1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804
</p>
</li>
<li>
<p>
RTDM_EXECUTE_ATOMICALLY() is deprecated and will be phased out in
  the next release. Drivers should prefer the newly introduced RTDM
  wait queues, or switch to the Cobalt-specific
  cobalt_atomic_enter/leave() call pair, depending on the use case.
</p>
</li>
</ul></div>
<div class="sidebarblock">
<div class="content">
<div class="title">Rationale</div>
<div class="paragraph"><p>This construct is not portable to a native implementation of RTDM, and
may be replaced by other means. The usage patterns of
RTDM_EXECUTE_ATOMICALLY() used to be:</p></div>
<div class="ulist"><ul>
<li>
<p>
somewhat abusing the big nucleus lock (i.e. nklock) grabbed by
  RTDM_EXECUTE_ATOMICALLY(), for serializing access to a section that
  should be given its own lock instead, improving concurrency in the
  same move. Such section does not call services from the Xenomai
  core, and does NOT specifically require the nucleus lock to be
  held. In this case, a RTDM lock (rtdm_lock_t) should be used to
  protect the section instead of RTDM_EXECUTE_ATOMICALLY().
</p>
</li>
<li>
<p>
protecting a section which calls into the Xenomai core, which
  exhibits one or more of the following characteristics:
</p>
<div class="ulist"><ul>
<li>
<p>
Some callee within the section may require the nucleus lock to
      be held on entry (e.g. Cobalt registry lookup). In what has to
      be a Cobalt-specific case, the new cobalt_atomic_enter/leave()
      call pair can replace RTDM_EXECUTE_ATOMICALLY(). However, this
      construct remains by definition non-portable to Mercury.
</p>
</li>
<li>
<p>
A set-condition-and-wakeup pattern has to be carried out
      atomically. In this case, RTDM_EXECUTE_ATOMICALLY() can be
      replaced by the wakeup side of a RTDM wait queue introduced in
      Xenomai 3 (e.g. rtdm_waitqueue_signal/broadcast()).
</p>
</li>
<li>
<p>
A test-condition-and-wait pattern has to be carried out
      atomically. In this case, RTDM_EXECUTE_ATOMICALLY() can be
      replaced by the wait side of a RTDM wait queue introduced in
      Xenomai 3 (e.g. rtdm_wait_condition()).
</p>
</li>
</ul></div>
</li>
</ul></div>
Philippe Gerum's avatar
Philippe Gerum committed
1805 1806
<div class="paragraph"><p>Please refer to kernel/drivers/ipc/iddp.c for an illustration of the
RTDM wait queue usage.</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824
</div></div>
<div class="ulist"><ul>
<li>
<p>
rtdm_irq_request/free() and rtdm_irq_enable/disable() call pairs
  must be called from a Linux task context, which is a restriction
  that did not exist previously with Xenomai 2.x.
</p>
</li>
</ul></div>
<div class="sidebarblock">
<div class="content">
<div class="title">Rationale</div>
<div class="paragraph"><p>Recent evolutions of the Linux kernel with respect to IRQ management
involve complex processing for basic operations
(e.g. enabling/disabling the interrupt line) with some interrupt types
like MSI. Such processing cannot be made dual-kernel safe at a
reasonable cost, without encurring measurable latency or significant
Philippe Gerum's avatar
Philippe Gerum committed
1825
code updates in the kernel.</p></div>
Philippe Gerum's avatar
Philippe Gerum committed
1826 1827 1828 1829 1830
<div class="paragraph"><p>Since allocating, releasing, enabling or disabling real-time
interrupts is most commonly done from driver initialization/cleanup
context already, the Cobalt core has simply inherited those
requirements from the Linux kernel.</p></div>
</div></div>
Philippe Gerum's avatar
Philippe Gerum committed
1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851
<div class="ulist"><ul>
<li>
<p>
The leading <em>user_info</em> argument to rtdm_munmap() has been
  removed.
</p>
</li>
</ul></div>
<div class="sidebarblock">
<div class="content">
<div class="title">Rationale</div>
<div class="paragraph"><p>With the introduction of RTDM file descriptors (see below) replacing
all <em>user_info</em> context pointers, this argument has become irrelevant,
since this operation is not related to any file descriptor, but rather
to the current address space.</p></div>
</div></div>
<div class="paragraph"><p>The new prototype for this routine is therefore</p></div>
<div class="listingblock">
<div class="content">
<pre><code>int rtdm_munmap(void *ptr, size_t len);</code></pre>
</div></div>
Philippe Gerum's avatar
Philippe Gerum committed
1852 1853 1854
<div class="ulist"><ul>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1855
Additional memory mapping calls
Philippe Gerum's avatar
Philippe Gerum committed
1856 1857
</p>
</li>
Philippe Gerum's avatar
Philippe Gerum committed
1858 1859 1860 1861 1862
</ul></div>
<div class="paragraph"><p>The new following routines are available to RTDM drivers, for mapping
memory over a user address space. They are intended to be called from
a &#8594;mmap() handler:</p></div>
<div class="ulist"><ul>
Philippe Gerum's avatar
Philippe Gerum committed
1863 1864
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1865 1866
rtdm_mmap_kmem() for mapping logical kernel memory (i.e. having
  a direct physical mapping).
Philippe Gerum's avatar
Philippe Gerum committed
1867 1868 1869 1870
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1871 1872
rtdm_mmap_vmem() for mapping purely virtual memory (i.e. with no
  direct physical mapping).
Philippe Gerum's avatar
Philippe Gerum committed
1873 1874 1875 1876
</p>
</li>
<li>
<p>
Philippe Gerum's avatar
Philippe Gerum committed
1877
rtdm_mmap_iomem() for mapping I/O memory.
Philippe Gerum's avatar
Philippe Gerum committed
1878 1879 1880
</p>
</li>
</ul></div>
Philippe Gerum's avatar
Philippe Gerum committed
1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901
<div class="listingblock">
<div class="content">
<pre><code>static int foo_mmap(struct rtdm_fd *fd, struct vm_area_struct *vma)
{
        ...
        switch (memory_type) {
        case MEM_PHYSICAL:
                ret = rtdm_mmap_iomem(vma, addr);
                break;
        case MEM_LOGICAL:
                ret = rtdm_mmap_kmem(vma, (void *)addr);
                break;
        case MEM_VIRTUAL:
                ret = rtdm_mmap_vmem(vma, (void *)addr);
                break;
        default:
                return -EINVAL;
        }
        ...
}</code></pre>
</div></div>
Philippe Gerum's avatar
Philippe Gerum committed
1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956
<div class="ulist"><ul>
<li>
<p>
the rtdm_nrtsig API has changed, the rtdm_nrtsig_init() function no
  longer returns errors, it has the void return type. The rtdm_nrtsig_t
  type has changed from an integer to a structure. In consequence, the
  nrtsig handler first argument is now a pointer to the rtdm_nrtsig_t
  structure.
</p>
</li>
</ul></div>
<div class="sidebarblock">
<div class="content">
<div class="title">Rationale</div>
<div class="paragraph"><p>Recent versions of the I-pipe patch support an ipipe_post_work_root()
service, which has the advantage over the VIRQ support, that it does not
require allocating one different VIRQ for each handler. As a consequence
drivers may use as many rtdm_nrtsig_t structures as they like, there is
no chance of running out of VIRQs.</p></div>
</div></div>
<div class="literalblock">
<div class="content">
<pre><code>The new relevant prototypes are therefore:</code></pre>
</div></div>
<div class="listingblock">
<div class="content">
<pre><code>typedef void (*rtdm_nrtsig_handler_t)(rtdm_nrtsig_t *nrt_sig, void *arg);

void rtdm_nrtsig_init(rtdm_nrtsig_t *nrt_sig,
     rtdm_nrtsig_handler_t handler, void *arg);</code></pre>
</div></div>
<div class="ulist"><ul>
<li>
<p>
a new rtdm_schedule_nrt_work() was added to allow scheduling a Linux
  work queue from primary mode.
</p>
</li>
</ul></div>
<div class="sidebarblock">
<div class="content">
<div class="title">Rationale</div>
<d